Graphics Plus/Graphics Plus.iso/msdos/raytrace/rt800/scn2sff.lst

File List | 1992-07-27 | 21KB | 567 lines

                                                      SCN2SFF(1G)

NAME
     scn2sff - format conversion program

SYNOPSIS
     scn2sff [options] {SCNfile|-} [>SFFfile]

AUTHOR
     Antonio Costa, INESC-Norte, 1991 1992

DESCRIPTION
     _s_c_n_2_s_f_f command performs conversion between a text format
     (SCN) suitable for scene descriptions to another more simple
     text format (SFF) that is accepted by the _r_t_r_a_c_e ray-tracer
     program.  The SCN text file describes objects, lights, sur-
     face definitions, textures, etc.  The scene format is
     described bellow.

OPTIONS
     [C]
     The parameter _C tells the program to preprocess the input
     file through the UNIX standard preprocessor (/usr/lib/cpp
     with option -P).

     [M]
     The parameter _M tells the program to preprocess the input
     file through the M4 preprocessor (/usr/bin/m4).

     [P"_p_r_e_p_r_o_c_e_s_s_o_r _c_o_m_m_a_n_d"]
     The parameter _P tells the program to preprocess the input
     file through the command described (for example,
     P"/usr/lib/cpp -P -Dabc").

RESTRICTIONS
     None for the moment.

BUGS
     No bugs known.  They have to be hidden deep somewhere, as
     usual.

DESCRIPTION
     Comments start with % ; or # characters and continue to the
     end of the line (so there are no nested comments).

     The commands are processed from the start of the scene, and
     some have a global effect until they are changed or the
     scene is complete. Such commands are _r_e_f_r_a_c_t_i_o_n, _s_u_r_f_a_c_e,
     _t_r_a_n_s_f_o_r_m_a_t_i_o_n_s and _t_e_x_t_u_r_e_s; as commands can be nested by
     grouping, any command defined inside a group is removed when
     that group is finished.

     Example:

     surface matte white        % current surface is matte white
     refraction 1.1             % current refraction index
     transform rotate x 15      % transformation
     group                      % start of a group of commands
       surface matte red        % new current surface
       transform scale 2        % transformation
       sphere 0 0 0 1           % sphere object
     ungroup                    % end of group
     % back to matte white surface, refraction 1.1
     % scale transformation is removed

                         ENTITIES

     The main entities are:

     _i_n_t_e_g_e_r - it can be a simple number, an integer expression
     enclosed in parenthesis or the _i_n_t function applied to any
     real expression.

     _r_e_a_l - a number, a function or an expression enclosed in
     parenthesis.

     _c_o_l_o_r - a triplet of RGB real values between 0 and 1 (in
     certain cases, it is allowed to be greater than 1 or nega-
     tive; called _c_o_l_o_r__e_x_t_e_n_d_e_d) or a name (like _r_e_d, _b_l_u_e,
     etc).

     _p_o_i_n_t - a triplet of XYZ values (numbers, functions or
     expressions).

     _v_e_c_t_o_r - similar to point, but the 3 components cannot be
     simultaneously equal to 0.

     _f_i_l_e_n_a_m_e - a set of characters with no blanks between.

     _e_x_p_r_e_s_s_i_o_n - anything enclosed in parenthesis. Operators are
     +, -, *, /, ^ (exponentiation) and | (remainder).

     _f_u_n_c_t_i_o_n - there are many functions available: _i_n_t _s_i_n _c_o_s
     _t_a_n _a_s_i_n _a_c_o_s _a_t_a_n _s_q_r_t _r_t_o_d _d_t_o_r _e_x_p _l_o_g _a_b_s _m_a_x _m_i_n. There
     also some functions that operate with vectors and return a
     number (_d_o_t_v_e_c_t_o_r) and some that return a vector or point
     (_n_o_r_m_v_e_c_t_o_r _a_d_d_v_e_c_t_o_r _d_i_f_f_v_e_c_t_o_r _s_c_a_l_e_v_e_c_t_o_r _c_r_o_s_s_v_e_c_t_o_r).
     There is also an operator _m_o_n_o that converts from a value to
     3 identical values (good for specifying monochromatic
     colors).

                         GENERAL COMMANDS

     The main commands are:

     _e_y_e (_f_r_o_m) point - default {5,0,0}.

     _l_o_o_k (_a_t) point - default {0,0,0}.

     _u_p vector - default {0,1,0}.

     _a_n_g_l_e (_f_o_v) horizontal [vertical] - half aperture view in
     degrees (default 22.5 degrees).

     _b_a_c_k_g_r_o_u_n_d color - the color of the background, at infinite
     distance (default light_sky_blue).

     _a_m_b_i_e_n_t color - the diffuse light that illuminates the whole
     scene (default is {0.1,0.1,0.1}).

     _r_e_f_r_a_c_t_i_o_n (_i_o_r) index - default is 1.

     _g_r_o_u_p ... _u_n_g_r_o_u_p - anything enclosed is only defined inside
     the block, ie, it does not apply outside.

                         LIGHT COMMANDS

     The commands for definition of light sources are:

     _l_i_g_h_t _p_o_i_n_t point [color_extended] - default color for
     lights is white.

     _l_i_g_h_t _d_i_r_e_c_t_i_o_n_a_l vector [color].

     _l_i_g_h_t _s_p_o_t point vector color_extended [angle [factor]] -
     the light illuminates inside a cone defined by the angle
     (default 45 degrees) and the transition can be sharp if fac-
     tor is near 1 or smooth if factor >> 1 (default 1).

     _l_i_g_h_t _e_x_t_e_n_d_e_d point color_extended radius samples - a
     spherical light (it is sampled by samples^2 rays).

                         SURFACE COMMANDS

     The commands for definition of surfaces are:

     _s_u_r_f_a_c_e color [diffusion specularity phong metalness [tran-
     sparency]] - phong and metalness are values, the others are
     colors (defaults {0.9,0.9,0.9} {0.1,0.1,0.1} 3 0
     {0.1,0.1,0.1} or transparency only {0,0,0}).

     _s_u_r_f_a_c_e _s_t_r_a_u_s_s color smoothness metalness [transparency] -
     all colors (default transparency is {0,0,0}).

     _s_u_r_f_a_c_e _m_a_t_t_e color - all diffuse surface.

     _s_u_r_f_a_c_e _p_l_a_s_t_i_c color smoothness phong - surface with big
     diffusion, small specularity and small phong factor.

     _s_u_r_f_a_c_e _m_e_t_a_l color smoothness phong - surface with small
     diffusion, big specularity, big phong factor and metalness
     factor equal to 1.

     _s_u_r_f_a_c_e _d_i_e_l_e_c_t_r_i_c color transparency refraction - tran-
     sparent surface with no diffusion, some specularity, large
     phong factor and null metalness.

     _s_u_r_f_a_c_e _g_l_a_s_s color transparency - transparent surface with
     refraction index equal to 1.52, approximately.

                         OBJECT COMMANDS

     The commands for objects are of the form
          _o_b_j_e_c_t object_data
     or else with local commands that apply only to itself of the
     form
          _o_b_j_e_c_t [attributes ... _d_a_t_a] object_data.

     _s_p_h_e_r_e center radius.

     _b_o_x center sizes - this is an axis-aligned box.

     _c_u_b_e center size - again it is axis-aligned.

     _c_o_n_e apex base base_radius - closed cone.

     _c_o_n_e _o_p_e_n apex base base_radius.

     _c_y_l_i_n_d_e_r apex base radius - closed cylinder.

     _c_y_l_i_n_d_e_r _o_p_e_n apex base radius.

     _c_o_n_e _t_r_u_n_c_a_t_e_d apex apex_radius base base_radius - closed.

     _c_o_n_e _t_r_u_n_c_a_t_e_d _o_p_e_n apex apex_radius base base_radius.

     _w_e_d_g_e point point point depth - defined by a triangular face
     and depth (face is defined counterclockwise so that depth is
     measured in the opposite direction of Rigth Hand Rule thumb;
     this convention also applies to other objects).

     _t_e_t_r_a point point point point.

     _p_r_i_s_m depth number_vertices point ... point - closed prism.

     _p_r_i_s_m _o_p_e_n depth number_vertices point ... point.

     _p_y_r_a_m_i_d depth number_vertices point ... point - closed
     pyramid.

     _p_y_r_a_m_i_d _o_p_e_n depth number_vertices point ... point.

     _p_y_r_a_m_i_d _t_r_u_n_c_a_t_e_d _o_p_e_n depth apex_scale number_vertices
     point ... point - it is an open pyramid with the apex scaled
     by apex_scale in relation to its base (if 0 it is an open
     pyramid, if 1 it is a prism).

     _d_i_s_c center normal radius.

     _r_i_n_g center normal outer_radius inner_radius.

     _p_a_t_c_h point ... point (12) - a bicubic patch is defined by
     its corners and 8 exterior points, arranged in this manner:
                       11  12
                     7  8  9  10
                     3  4  5  6
                        1  2
     Normal points according to Right Hand Rule using corners 4-
     5-9-8.

     _p_a_t_c_h _f_i_l_e [point [point]] filename - a group of patches
     stored in a file; first point is a translation and second is
     a scale.

     _p_o_l_y_g_o_n number_vertices point ... point - a polygon (can be
     concave, but does not have holes).

     _p_o_l_y_g_o_n _f_i_l_e [point [point]] filename - a group of polygons
     stored in a file; first point is a translation and second is
     a scale.

     _t_r_i_a_n_g_l_e point point point.

     _q_u_a_d_r_a_n_g_l_e point point point point.

     _t_r_i_a_n_g_l_e _n_o_r_m_a_l point vector point vector point vector - a
     triangle with normals in its vertices.

     _t_r_i_a_n_g_l_e _n_o_r_m_a_l _f_i_l_e point point filename - a group of tri-
     angles with normals in the vertices stored in a file; first
     point is a translation and second is a scale.

     _t_o_r_u_s outer_radius section_radius start_angle end_angle
     [outer_samples section_samples] - A closed torus is centered
     in {0,0,0} and lies in the XZ plane. 0 degrees is in the X
     direction and the angle increases counterclockwise.

     _t_o_r_u_s _o_p_e_n outer_radius section_radius start_angle end_angle
     [outer_samples section_samples] - An open torus.

     _t_e_x_t_3_d _f_i_l_e filename - a group of text primitives stored in
     a file; each primitive is described by lines and arcs and is
     extruded (similar to a prism, in a certain way).

     _c_s_g begin - start of a CSG primitive, ie, left component.

     _c_s_g next - right component of a CSG primitive.

     _c_s_g end - end of a CSG primitive.

     _l_i_s_t begin - start of a list primitive (no nesting allowed).

     _l_i_s_t end - end of a list primitive.

                         TRANSFORMATION COMMANDS

     A transformation may be defined globaly or inside a block,
     and it is post-concatenated with previous transformations.
     If inside a block, when the block is terminated the
     transformations defined inside it are removed. Also, when a
     transformation is an attribute of an object or texture it
     only exists for that entity.

     _t_r_a_n_s_f_o_r_m _n_o_n_e - removes all transformations.

     _t_r_a_n_s_f_o_r_m _s_c_a_l_e factor [factor factor].

     _t_r_a_n_s_f_o_r_m _t_r_a_n_s_l_a_t_e point.

     _t_r_a_n_s_f_o_r_m _r_o_t_a_t_e _x angle.

     _t_r_a_n_s_f_o_r_m _r_o_t_a_t_e _y angle.

     _t_r_a_n_s_f_o_r_m _r_o_t_a_t_e _z angle.

     _t_r_a_n_s_f_o_r_m _r_o_t_a_t_e axis angle.

     _t_r_a_n_s_f_o_r_m _g_e_n_e_r_a_l point point point [point].

                         TEXTURE COMMANDS

     A texture is basically a modification of the surface charac-
     teristics of an object, a modification of the normal vector
     in the intersection point or the modification of the inter-
     section point itself. It is possible to apply transforma-
     tions to textures, and even keep them independent from the
     object transformations.

     _t_e_x_t_u_r_e _n_o_n_e - remove all defined textures.

     _t_e_x_t_u_r_e _s_c_a_l_e factor [factor factor].

     _t_e_x_t_u_r_e _t_r_a_n_s_l_a_t_e point.

     _t_e_x_t_u_r_e _r_o_t_a_t_e _x angle.

     _t_e_x_t_u_r_e _r_o_t_a_t_e _y angle.

     _t_e_x_t_u_r_e _r_o_t_a_t_e _z angle.

     _t_e_x_t_u_r_e _r_o_t_a_t_e axis angle.

     _t_e_x_t_u_r_e _g_e_n_e_r_a_l point point point [point].

     _t_e_x_t_u_r_e _l_o_c_a_l - generate all the transformations necessary
     to access the object directly, without considering any
     object transformations previously defined.

     _c_h_e_c_k_e_r_s surface [transform] - a chessboard-like pattern of
     the current surface and the defined surface.

     _b_l_o_t_c_h scale surface [filename] [transform] - A spray-like
     mixture of 2 surfaces (the current and the defined). The
     scale controls the mixture. If a filename is given, it is
     interpreted as a color palette, and it must contain 256 tri-
     plets of RGB values in the range 0 to 255 (this format is
     equal for all the textures that have a _f_i_l_e_n_a_m_e parameter,
     except _i_m_a_g_e_m_a_p).

     _b_u_m_p scale [transform] - A normal-modifying texture.

     _m_a_r_b_l_e [filename] [transform] - A marble-like texture.

     _f_b_m offset scale omega lambda threshold octaves [filename]
     [transform] - A fractal brownian motion texture that changes
     diffusion and specularity.

     _f_b_m_b_u_m_p offset scale lambda octaves [transform] - a texture
     that modifies the normal.

     _w_o_o_d color [transform] - A texture imitating wood (default
     color is _b_r_o_w_n).

     _r_o_u_n_d scale [transform] - strange texture that modifies dif-
     fusion and specularity.

     _b_o_z_o turbulence [filename] [transform].

     _r_i_p_p_l_e_s frequency phase scale [transform] - a texture that
     imitates ripples (small sinusoidal perturbations of the sur-
     face).

     _w_a_v_e_s frequency phase scale [transform] - a texture like
     waves (multi-interfering sinusoidal perturbations of the
     surface).

     _s_p_o_t_t_e_d [filename] [transform] - small color spots.

     _d_e_n_t_s scale [transform] - small modifications of normal that
     imitate dents.

     _a_g_a_t_e [filename] [transform].

     _w_r_i_n_k_l_e_s [transform] - a texture that modifies normal imi-
     tating wrinkles.

     _g_r_a_n_i_t_e [filename] [transform].

     _g_r_a_d_i_e_n_t turbulence direction [filename] [transform] - This
     texture produces a variation of color following direction
     given.

     _i_m_a_g_e_m_a_p turbulence mode u_axis v_axis filename [transform]
     - An image-mapping texture. Mode parameter controls tiling
     of texture (0-yes, nonzero-no).  The u_axis and v_axis
     specify the internal texture axis from the 3D axis (1-X, 2-
     Y, 3-Z).  A filename must be given, because it is the image
     that will be drawn on the surface (the format of the image
     is the _r_t_r_a_c_e format PIC).

     _g_l_o_s_s scale [transform] - Glossy-like texture that changes
     diffusion, specularity and phong factor.

     _b_u_m_p_3 scale size [transform] - A normal-modifying texture.
     Changes intersection point, so may produce strange results!

EXAMPLES
     Here are some simple examples:

     %%%%% example 1
     % light source
     light point 4 3 1
     % surface
     surface matte red
     sphere 0 0 0 1
     % another surface (replaces previous)
     surface plastic blue mono 0.3 0.3
     sphere 3 -0.4 0.4 0.2
     % another surface
     surface plastic yellow mono 0.9 0.9
     % transformations for next object(s)
     transform rotate y rtod(atan(1))
     transform translate 3 -0.4 -0.4
     box 0 0 0 0.1 0.1 0.3
     % remove previous transformation(s)
     transform none
     % another surface
     surface green mono 0.8 mono 0.2 10 0.3
     cone 3 0.1 0 3 -0.4 0 0.2
     surface matte white
     csg subtraction begin
         sphere 0 0 0 1
         csg next
         box 0 0 0 1.1 0.4 0.4
     csg end

     This example is correct, although it does not take full
     usage of SCN, ie, the capability of defining locally the
     attributes. It could be rewritten:

     %%%%% example 2
     % light source
     light point 4 3 1
     % now all objects have local attributes
     sphere
         surface matte red
         data 0 0 0 1
     sphere
         surface plastic blue mono 0.3 0.3
         data 3 -0.4 0.4 0.2
     box
         surface plastic yellow mono 0.9 0.9
         % local transformations
         transform rotate y rtod(atan(1))
         transform translate 3 -0.4 -0.4
         % this object is defined in a local coords system
         % the translation puts it in the right place
         data 0 0 0 0.1 0.1 0.3
     cone
         surface green mono 0.8 mono 0.2 10 0.3
         data 3 0.1 0 3 -0.4 0 0.2
     csg subtraction surface matte white
         data begin
         sphere 0 0 0 1
         csg next
         box 0 0 0 1.1 0.4 0.4
     csg end

     To produce an image from any of these examples, the example
     should be stored in a file (suppose _e_x_a_m_p_l_e._s_c_n) and then
     execute
       scn2sff example.scn|rtrace w512 p2 A0.1 - example.pic
     to create the image.  If the SCN file contained any _c_p_p
     preprocessor directives, then
       scn2sff C example.scn|rtrace w512 p2 A0.1 - example.pic
     would do.

     A complete demo example follows:
     [Start]
     % example to be traced with parameters like
     % w512 p2 A0.1 t1 I1 - good quality
     % or then
     % w512 p3 A.05 t1 I1 j1 - very good quality

     %%%%% start
     eye 5 2 2
     fov 20
     background light_sky_blue
     ambient mono 0.2 % dark grey

     light point 3 5 4 white

     surface matte red % default surface

     %%%%% a simple CSG example
     csg subtraction begin
     % no attributes for this CSG, so it uses the attributes
     % of its nodes...

       % left node
       csg subtraction
         % attributes of this CSG object
         surface matte white
         texture scale 0.2
         checkers surface matte mono 0.3 translate 0.1 0.1 0.1
         data begin

         box 0 0 0 1 1 1

       csg next

         box 0 0 0 1.01 0.5 0.5
         list begin
           % a cylinder must be enclosed in a list, because it is
           % not a closed object, but 3 objects joined together
           cylinder 0 1.01 0 0 -1.01 0 0.5
         list end

       csg end

     csg next

       % right node
       sphere 1 1 1 0.5 % default surface assumed
       sphere 1 1 -1 0.5
       sphere surface matte blue data 1 -1 1 0.5
       sphere surface matte blue data 1 -1 -1 0.5

     csg end

     %%%%% some 3D text
     text3d file surface matte yellow
       data csg.t3d % data is in file

     %%%%% end
     [End]

     The csg.t3d file contents could be:
     [Start]
     SPACING 0.1
     ORIENTATION 0 0 -1 0 1 0 1 0 0
     ENCODING abc.ppe
     FONT zurichcg.ppf
     SCALE 0.4 0.4 0.2
     AT 1.25 1.5 1.6 "Antonio Costa"
     FONT renfrew.ppf
     SCALE 0.4 0.4 0.1
     AT 1.1 -0.85 1.1 "/copyright/1992"
     AT 1.1 -1.3 1.1 "INESCn"

     # there must be an empty line in the end
     Description:
     SPACING is letter spacing
     ORIENTATION defines how the text appears
      - 1st: text direction vector (left to right)
      - 2nd: vertical vector
      - 3rd: depth vector
     ENCODING associates logical character names to glyph numbers
     FONT is the file where the 2D glyphs are defined
     SCALE controls scaling along ORIENTATION vectors
     AT is baseline lower left position of text plus text
     (quoted)
     [End]

HISTORY
     Copyright (C) 1991 1992 by Antonio Costa.
     Permission is granted to use this file in whole or in part
     for any purpose, educational, recreational or commercial,
     provided that this copyright notice is retained unchanged.
     This software is available to all free of charge by
     anonymous FTP.

     23-Jul-92  Antonio Costa at INESC-Norte
          Release 1.3.1
          [e-mail] [e-mail]